Introduction

Here comes the central purpose of simlandr: constructing the potential landscapes from simulation results.

The landscape function is calculated based on the steady state distribution of the system:

\[U = -\ln P_\textrm{SS}\]

My colleagues and I are writing a paper about the detail of this method. I will put the link here as soon as we finish that.

simlandr provides a set of tools to construct 2d, 3d, and 4d landscapes from single or multiple simulation results. These methods will be illustrated in the following sections.

Single simulation landscape

The landscapes in this section are only from a single simulation. We first make a simulation series for illustration.

single_test <- sim_fun_test(
  par1 = list(var1 = 1),
  par2 = list(var2 = 1, var3 = 0)
)

The result of the landscape functions are landscape objects, which contains the landscape plot as well as the smooth distributions that are used to calculate the landscapes. Plots without z-axis are built with ggplot2 package, while plots with z-axis are built with plotly package. These plots can also be modified using ggplot2 or plotly functions.

You can use plot(l) to access those plots. For some types of landscapes, there are multiple types of plots available. Use plot(l, index = 2) or plot(l, index = 3), etc. to access those plots.

Below are the examples of available plots. The meaning of the parameters can be found at the helping page of each function.

2d (x, y) plot

l_single_2d <- make_2d_density(single_test, x = "out1", from = -2, to = 2, adjust = 1)
plot(l_single_2d)

3d (x, y, z) or (x, y, color) plot

l_single_3d <- make_3d_static(single_test, x = "out1", y = "out2", lims = c(-3, 3, -3, 3), h = 0.01, kde_fun = "ks")
#> Calculating the smooth distribution...
#> Done!
#> Making the plot...
#> Done!
#> Making the 2d plot...
#> Done!

plot(l_single_3d, 1)
plot(l_single_3d, 2)

4d (x, y, z, color) plot

l_single_4d <- make_4d_static(single_test, x = "out1", y = "out2", z = "out3", lims = c(-3, 3, -3, 3, -3, 3), h = 0.01)
#> Calculating the smooth distribution...
#> Done!
#> Making the plot...
#> Done!
plot(l_single_4d) %>% plotly::layout(scene = list(zaxis=list(range = c(-3,3))))

Multiple simulation landscape

The landscapes in the section are build from batch simulation results. The following two data sets will be used to illustrate the functions. The difference is that batch_test_result only contains one varying parameter, whereas batch_test_result2 contains two.

batch_test <- new_var_set()

batch_test <- batch_test %>%
  add_var("par2", "var3", 0, 0.5, 0.1)

batch_test_grid <- make_var_grid(batch_test)

batch_test_result <- batch_simulation(batch_test_grid, sim_fun_test,
  default_list = list(
    par1 = list(var1 = 0),
    par2 = list(var2 = 0, var3 = 0)
  ),
  bigmemory = FALSE
)
batch_test_result
#> Output(s) from 6 simulations.

batch_test2 <- new_var_set()
batch_test2 <- batch_test2 %>%
  add_var("par1", "var1", -0.2, 0.2, 0.2) %>%
  add_var("par2", "var2", -0.2, 0.2, 0.2)
batch_test_grid2 <- make_var_grid(batch_test2)

batch_test_result2 <- batch_simulation(batch_test_grid2, sim_fun_test,
  default_list = list(
    par1 = list(var1 = 0),
    par2 = list(var2 = 0, var3 = 0)
  ),
  bigmemory = FALSE
)
batch_test_result2
#> Output(s) from 9 simulations.

Below are the examples of available plots.

2d (x, y) plot series with one varying parameter or plot matrix with two varying parameters

l_batch_2d_m1 <- make_2d_matrix(batch_test_result, x = "out1", cols = "var3", from = -3, to = 3, adjust = 0.1)
#> Making the plot...
#> Done!
plot(l_batch_2d_m1)


l_batch_2d_m2 <- make_2d_matrix(batch_test_result2, x = "out1", rows = "var1", cols = "var2", from = -1, to = 1, adjust = 0.1)
#> Making the plot...
#> Done!
plot(l_batch_2d_m2)

3d (x, y, color) plot series with one varying parameter or plot matrix with two varying parameters

l_batch_3d_m1 <- make_3d_matrix(batch_test_result, x = "out1", y = "out2", cols = "var3", lims = c(-3, 3, -3, 3), h = 0.001, kde_fun = "ks", zmax = 10)
#> Making the 2d plot...
#> Done!
plot(l_batch_3d_m1)


l_batch_3d_m2 <- make_3d_matrix(batch_test_result2, x = "out1", y = "out2", rows = "var1", cols = "var2", lims = c(-3, 3, -3, 3), h = 0.001, kde_fun = "ks", zmax = 10)
#> Making the 2d plot...
#> Done!
plot(l_batch_3d_m2)

3d (x, y, z) or (x, y, color) animation and 3d (x, y, color) plot series with one varying parameter

gifski package is needed to show the 3d (x, y, color) animation.

l_batch_3d_a <- make_3d_animation(batch_test_result, x = "out1", y = "out2", fr = "var3", zmax = 20, lims = c(-3, 3, -3, 3), h = 0.002)
#> Wrangling data...
#> Done!
#> Making the plot...
#> Done!
#> Making the 2d plot...
#> Done!
#> Making the 3d matrix...
#> Making the 2d plot...
#> Done!
#> Done!

plot(l_batch_3d_a, 1)
plot(l_batch_3d_a, 2) #> Warning: No renderer available. Please install the gifski, av, or magick package #> to create animated output #> NULL plot(l_batch_3d_a, 3)